<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	<link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css">		
<title>FAQ</title>
</head>

<body>
<div class="app">

<h1>FAQ</h1>

<![CDATA[=========================================================]]>

<div class="h2"><!-- no 'id' or 'title' attribute for TOC -->
<h2>Table of Contents</h2>

<h4>General questions:</h4>
<ul>
<li><a href="#why">Why does this project exist?</a></li>
<li><a href="#version">Does Subclipse support Eclipse X.Y or Websphere Studio X.Y?</a></li> 
<li><a href="#adapter">What is an adapter?  What is JavaHL?</a></li> 
<li><a href="#adapter-choice">Which adapter should I use?</a></li> 
<li><a href="#passwords">Usernames and passwords.</a></li> 
</ul>

<h4>How-to:</h4>
<ul>
<li><a href="#checkout">How do I check out the Subclipse code?</a></li>
<li><a href="#repository">How do I create a repository?  How do I
    import data into it?</a></li> 
<li><a href="#cvs2svn">How do I convert an existing CVS repository
    into a Subversion repository?</a></li>
<li><a href="#http-proxy">How do I configure an HTTP proxy connection?</a></li>
<li><a href="#http-ssl">How do I specify SSL client certificates?</a></li>
<li><a href="#svn-ssh">How do I configure an svn+ssh:// connection?</a></li>
</ul>

<h4>Troubleshooting:</h4>
<ul>
<li><a href="#get-javahl">How do I get the JavaHL library for my operating system?</a></li>
<li><a href="#build-javahl">How do I build JavaHL from source?</a></li>
<li><a href="#library-path">I think I have a valid JavaHL library installed, but Subclipse
    says it is not found.  What should I do?</a></li>
<li><a href="#path-case">Why am I getting an error dialog telling me the case of my Eclipse workspace
path does not match the filesystem?  Windows does not seem to care.</a></li>
</ul>

</div>

<![CDATA[=========================================================]]>

<hr/>

<div class="h2" id="general-questions" title="general-questions">
<h2>General questions:</h2>

<![CDATA[-----------------------------------------------------------]]>

<div class="h3" id="why" title="why">
<h3>Why does this project exist?</h3>

<p>Subclipse exists to provide an outstanding user interface to Subversion from
within the Eclipse IDE.  We aim to provide a client that is every bit as robust
and user-friendly as the CVS client that comes with Eclipse.  That being said,
there are a lot of major technical differences between Subversion and CVS.  Therefore, we
try to strike a balance between providing a UI that will be familiar to experienced Eclipse
CVS users, and one that is appropriate for the Subversion action being exposed.  In particular,
the way that Subversion handles branches and tags is very, very different from CVS.  Consequently
the UI for these features in Subclipse is different than the UI for the CVS client.</p>

</div>

<![CDATA[-----------------------------------------------------------]]>

<div class="h3" id="version" title="version">
<h3>Does Subclipse support Eclipse X.Y or Websphere Studio X.Y?</h3>

<p>Subclipse should support any IDE or application that is built on the Eclipse
framework.  The Subclipse feature has the appropriate &lt;requires&gt; tags to define
the Eclipse features that we require.  The current version of Subclipse supports
Eclipse 3.x.  There is an older version of Subclipse that supports Eclipse 2.x and applications
that are based on it, such as WebSphere Studio 5.x.  That version of Subclipse is no longer
supported or actively developed.
</p>

</div>

<![CDATA[-----------------------------------------------------------]]>

<div class="h3" id="adapter" title="adapter">
<h3>What is an adapter?  What is JavaHL?</h3>

<p>Unlike CVS, which does not have an official API, Subversion was designed from the
start to be an API.  Subversion is written (in C) as a set of libraries.  Subversion then provides
a default UI, in the form of a command line interface, that uses these libraries.  Subversion
also provides language bindings for various programing languages so that these same libraries can
be used in your language of choice.  JavaHL is the name of the Java language binding provided by
the Subversion project.  JavaHL is an official part of the Subversion project, not the Subclipse project.<br /><br />
svnClientAdapter is a Java project that was developed for Subclipse.  It provides an even higher level
of abstraction to the Subversion libraries.  It also allows for different ways of accessing Subversion
functionality.  Historically, the two options were to use the JavaHL library or the Subversion
command line.  Recently, a third option was added and that is to use the <a href="http://svnkit.com/">
SVNKit</a> library which is a 100% Pure Java implementation of the protocols used by Subversion.  
This option has the advantage of not requiring any native libraries installed on the client.  Of course,
since SVNKit does not utilize the Subversion libraries it does not have the guaranteed compatability that
you can expect from JavaHL or the command line adapters.  That being said, SVNKit is tested against the same
test suite that tests the Subversion command line, and passes those tests.<br /><br />
SVNKit does not currently support the file:// protocol but there are plans to add support for accessing
fsfs repositories in the future.</p>

</div>

<![CDATA[-----------------------------------------------------------]]>

<div class="h3" id="adapter-choice" title="adapter-choice">
<h3>Which adapter should I use?</h3>

<p>If the JavaHL library is available on your system, or easily attainable, then it is
probably the best choice.  That being said, SVNKit is a great option and offers a number of
significant features that JavaHL does not currently offer.  JavaHL is currently your only
option if you have to use file:// protocol.  In that scenario, you should really consider
running a local svnserve instance and using the svn:// protocol.</p>

</div>

<![CDATA[-----------------------------------------------------------]]>

<div class="h3" id="passwords" title="passwords">
<h3>Usernames and passwords</h3>

<p>When you define a repository connection to Subclipse there is an area to specify your
username and password.  Since version 0.9.30 of Subclipse the best thing to do is always leave
these fields empty.  The exception is if you are using the command line adapter.  As of version 0.9.100
the dialogs no longer show the username and password fields.  
Why should you leave them blank?  Because the JavaHL and SVNKit
adapters are intelligent enough to prompt you for this information when they need to.  You can also
then allow the adapter to cache this information.  The adapters are also intelligent enough to prompt
you when the password has changed.  Conversely, if you specify a username and password within Subclipse
then we supply that username and password to the adapter.  If the password has changed on the server,
then the adapter will prompt you for a new one.  Now we get to the problem.  Subclipse does not know
that this exchange took place so it has no way to update its password.  Consequently you keep getting
prompted by the adapter for your password.</p>
<p>If you just leave these fields blank within Subclipse, then you never have to worry about it.  If
you do provide a username and password to Subclipse, and your password changes, you can update the
stored values by right-clicking on the connection in the SVN Repository view and choosing the Properties
option.
</p>

</div>

</div>

<div class="h2" id="how-to" title="how-to">
<h2>How-to:</h2>

<![CDATA[-----------------------------------------------------------]]>

<div class="h3" id="checkout" title="checkout">
<h3>How do I check out the Subclipse code?</h3>

<p>The URL for the Subclipse repository is http://subclipse.tigris.org/svn/subclipse/.  If
you have at least the Observer role in the Subclipse project, then provide your tigris.org
username and password when prompted.  Otherwise use a value of "guest" for each.  Subclipse
development is currently active on trunk.</p>

</div>

<![CDATA[-----------------------------------------------------------]]>

<div class="h3" id="repository" title="repository">
<h3>How do I create a repository?  How do I import data into it?</h3>

<p>Subclipse does not provide anything that allows you to create a Subversion repository.  That
action has to be performed outside of Eclipse.  Within Subclipse, you define a "connection" to
an already existing repository.  Defining a connection is one of the first things you should do
when using Subclipse.  This is done from the Subclipse Repository Exploring perspective.
</p>

<p>As for importing data, there are numerous ways it can be done, including doing it from outside
of Eclipse.  Assuming you have an existing project in your Eclipse workspace that you want to add to
your repository, you need to right-click on the project and do Team -&gt; Share Project.  Then follow
the wizard.
</p>

</div>

<![CDATA[-----------------------------------------------------------]]>

<div class="h3" id="cvs2svn" title="cvs2svn">
<h3>How do I convert an existing CVS repository
    into a Subversion repository?</h3>

<p>Members of the Subversion development community created and
maintain a tool called cvs2svn.  You can find it at <a
href="http://cvs2svn.tigris.org/">http://cvs2svn.tigris.org/</a>.  Be
sure to read the <a
href="http://cvs2svn.tigris.org/cvs2svn.html">cvs2svn documentation</a>.

</p>

<p>If cvs2svn.py does not work for you, (e.g. your repository
causes it to crash, or it doesn't deal with branches and tags
quite how you would like), there are at least two other
conversion utilities you can try.  These have different features
(and possibly different bugs):</p>

<ul>

<li>One based on <a
href="http://public.perforce.com/public/revml/index.html">VCP</a>
written by Chia-liang Kao can be found on <a
href="http://search.cpan.org/perldoc?VCP::Dest::svk">CPAN</a>.</li>

<li>refinecvs written by Lev Serebryakov is at <a
href="http://lev.serebryakov.spb.ru/refinecvs/"
>http://lev.serebryakov.spb.ru/refinecvs/</a>.</li>

</ul>

<p>See also the <a href="http://subversion.tigris.org/project_links.html">Subversion links</a>
page.</p>

</div>

<![CDATA[-----------------------------------------------------------]]>

<div class="h3" id="http-proxy" title="http-proxy">
<h3>How do I configure an HTTP proxy connection?</h3>

<p>If you are using the JavaHL or command-line client adapter then all communication with
your repository is performed by the Subversion libraries.  Consequently, the configuration
is the same as what you would do for the Subversion command line.  See: <a 
href="http://svnbook.red-bean.com/en/1.1/ch07.html#svn-ch-7-sect-1">
http://svnbook.red-bean.com/en/1.1/ch07.html#svn-ch-7-sect-1</a> for more information.</p>
<p>If you are using the SVNKit command-line client adapter then see: <a
href="http://svnkit.com/kb/user-guide-config-settings.html">http://svnkit.com/kb/user-guide-config-settings.html</a>
for more information.</p>

</div>

<![CDATA[-----------------------------------------------------------]]>

<div class="h3" id="http-ssl" title="http-ssl">
<h3>How do I specify SSL client certificates?</h3>

<p>If you are using the JavaHL or SVNKit adapters, then, at least in theory, you
should be prompted when/if you need to supply the server with a client certificate.
Just as you are when using the command-line.  As of the writing of this FAQ entry, at least
JavaHL has not implemented this prompting.  Consequently, you need to store your client
certificate in the Subversion configuration area.   See: <a 
href="http://svnbook.red-bean.com/en/1.1/ch07.html#svn-ch-7-sect-1">
http://svnbook.red-bean.com/en/1.1/ch07.html#svn-ch-7-sect-1</a> for more information.</p>

</div>

<![CDATA[-----------------------------------------------------------]]>

<div class="h3" id="svn-ssh" title="svn-ssh">
<h3>How do I configure an svn+ssh:// connection?</h3>

<p>If you are using the JavaHL or command-line client adapter then all communication with
your repository is performed by the Subversion libraries.  Consequently, the configuration
is the same as what you would do for the Subversion command line.  See: <a 
href="http://svnbook.red-bean.com/en/1.1/ch07.html#svn-ch-7-sect-1">
http://svnbook.red-bean.com/en/1.1/ch07.html#svn-ch-7-sect-1</a> for more information.  For
Windows users, here is a great explanation of how to set this up from our mailing list
archives: <a href="http://subclipse.tigris.org/servlets/ReadMsg?list=users&msgNo=3334">
Configuring svn+ssh:// on Windows</a>.
</p>
<p>As of Subclipse 0.9.35 if you are using the SVNKit client adapter you should be
dynamically prompted for your SSH username, password, keyfile, port etc...  When defining the
repository connection in Subclipse, simply specify the URL like svn+ssh://hostname/repos.  Do
not include your username in the URL and do not provide a username and password in the connection
dialog.  At runtime, SVNKit will prompt you for your SSH credentials and optionally cache them in
the Eclipse keyring.  If you are not prompted for your credentials, it may be because you have
previously attempted to manually configure SVNKit.  If so, then you should "undo" all of that
manual configuration.  The older manual configuration is documented at: <a
href="http://svnkit.com/kb/user-guide-config-settings.html">http://svnkit.com/kb/user-guide-config-settings.html</a>.</p>
</div>

</div>

<div class="h2" id="troubleshooting" title="troubleshooting">
<h2>Troubleshooting:</h2>

<![CDATA[-----------------------------------------------------------]]>

<div class="h3" id="get-javahl" title="get-javahl">
<h3>How do I get the JavaHL library for my operating system?</h3>

<p><b>Windows:</b>&nbsp;JavaHL is included as part of Subclipse.  You do not
need to do anything.</p>

<p><b>OS X:</b>&nbsp;We recommend that you install the Metissian Subversion package.
This package includes JavaHL and installs everything in a way that it is recognized by Subclipse.
Download the package at <a href="http://metissian.com/projects/macosx/subversion/">
http://metissian.com/projects/macosx/subversion/</a>.</p>

<p><b>Linux:</b>&nbsp;The answer varies by distribution and the packaging mechanism.  In general
most distributions do NOT include the JavaHL library in their Subversion package.  In most cases,
you can download the source package and alter the build spec to build JavaHL.</p>
<p>There are Debian packages available for Subversion with JavaHL enabled. 
The packages are provided by http://www.ggtools.net/.  Here is the sources.list entry:</p>
<pre>
deb http://www.ggtools.net/files/debian/unstable/ ./
</pre>
<p>There are also binary RPM packages for SUSE available.  The main Subversion RPM 
package includes JavaHL by default.  These can be obtained at <a
href="http://ftp.suse.com/pub/projects/apache/subversion/">http://ftp.suse.com/pub/projects/apache/subversion/</a>. 
</p>
<p><b>Others:</b>&nbsp;If your packaging mechanism does not include the JavaHL library, then
you probably need to build the library from source.</p>

</div>

<![CDATA[-----------------------------------------------------------]]>

<div class="h3" id="build-javahl" title="build-javahl">
<h3>How do I build JavaHL from source?</h3>

<p>JavaHL is part of the Subversion project.  So to begin, you probably want to download
the latest source tarball.  See: <a href="http://subversion.tigris.org/project_packages.html">
http://subversion.tigris.org/project_packages.html</a>.  You should refer to the Subversion instructions
for detailed information, but on a *nix system the general procedure is this:</p>
<pre>
./configure --your-other-flags=here --enable-javahl --with-jdk=$JAVA_HOME\
     --with-jikes=$JAVA_HOME/bin/javac
make
make javahl
make install
make install-javahl
</pre>
<p>The main part to check before running the above command is "--your-other-flags". 
You will typically at least want --enable-ssl.
</p>

</div>

<![CDATA[-----------------------------------------------------------]]>

<div class="h3" id="library-path" title="library-path">
<h3>I think I have a valid JavaHL library installed, but Subclipse
    says it is not found.  What should I do?</h3>

<p>Starting with Subclipse 0.9.33 we now show the errors that occurred when loading
the JavaHL library.  To see these errors open the Eclipse preferences and go to Team -&gt; SVN.
Then click on JavaHL in the adapter section, the error messages should appear in a dialog.<br /><br />
On *nix systems the problem is almost always that the JavaHL library was not found in the java.library.path.
The Sun JVM only looks in the value of LD_LIBRARY_PATH, and on many *nix systems this value is not
defined.  The easiest workaround is to create a shell script that launches Eclipse:</p>
<pre>
export LD_LIBRARY_PATH=/usr/local/lib:.
./eclipse
</pre>
<p>Alternatively, you can also do something like this in your script:</p>
<pre>
./eclipse -vmargs -Djava.library.path=/usr/local/lib
</pre>

</div>

<![CDATA[-----------------------------------------------------------]]>

<div class="h3" id="path-case" title="path-case">
<h3>Why am I getting an error dialog telling me the case of my Eclipse workspace
path does not match the filesystem?  Windows does not seem to care.</h3>

<p>The underlying problem here is in Eclipse, see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=95832">
Bug#: 95832</a>.  Eclipse does not canonicalize the workspace path to match the
case of the underlying OS.  That alone would not be a problem, but Eclipse also has
code which relies on an exact string match when converting a path represented as a
String to an Eclipse resource.  When Subclipse calls Subversion API's, Subversion
naturally passes back paths in their exact case from the file system.  Subclipse then
has to take those Strings and convert them to an Eclipse IResource.  The Eclipse code
to do this fails if the case of the string does not match exactly with the value that
Eclipse has stored for the workspace.
</p>
<p>This problem was causing a lot of problems for Subclipse users and it took a long
time before the underlying cause was discovered.  See Subclipse <a
href="http://subclipse.tigris.org/issues/show_bug.cgi?id=285">issue# 285</a>
and all of the duplicates.  Since we cannot fix the Eclipse problem and this problem
is so hard for a user to self-diagnose, we added in our own check which displays a
warning dialog when we detect this situation exists.  The validation code looks like
this:</p>
<pre>
 public static boolean validateWorkspacePath() {
    File file = ResourcesPlugin.getWorkspace().getRoot().getLocation().toFile();
    String canonicalPath = null;
    try {
       canonicalPath = file.getCanonicalPath();
    } catch (IOException e) {
        e.printStackTrace();
    }
    if (!file.getAbsolutePath().equals(canonicalPath)) {
        MessageDialog.openError(Display.getCurrent().getActiveShell(), Policy.bind("WorkspacePathValidator.title"),
         Policy.bind("WorkspacePathValidator.eclipsePath") + "\n\n"  + file.getAbsolutePath() + 
         "\n\n" + Policy.bind("WorkspacePathValidator.fileSystemPath") + "\n\n" + canonicalPath +
         "\n\n" + Policy.bind("WorkspacePathValidator.instructions"));
        return false;
    }
    return true;
 }
</pre>
<p><b>NOTE:</b> We recently discovered that this basic issue was causing another problem users were seeing.  In this case
it happens when you use File -&gt; Import to import a project and you do not specify the correct case when importing.  This
leads to the same null resource problem.  In this scenario, we are now logging a very detailed error in the SVN Console and
Eclipse error log.  It also points to this FAQ.  In recreating the problem it appeared that the SVNKit adapter did not
have the problem.  Possibly because it is using the same Java API's as Eclipse the case does not get canonicalized as it does
when using the JavaHL native C libraries.  Other than switching to SVNKit, the way to solve the problem in this scenario would
be to delete the project from the workspace and re-import it.  Use the Eclipse file chooser to select the project so that the
case matches the OS.</p>

</div>
</div>

</div>
</body>
</html>
